Pull Request

Description

Removes the die() helper from the GitLab skill so GitLabError becomes the module's single failure mechanism, and adds a source contract so the boundary cannot drift again.

GitLabError is the module-wide typed failure base. GitLabAPIError(GitLabError) is the API-specific subclass used for transport failures; non-transport validation, configuration, and command errors remain GitLabError.

This closes the last open acceptance criterion of #1555. The other seven criteria — LOGGER, the _emit output sink, _emit_debug_traceback, typed API error classes, the source-contract tests, and the gitlab_token global removal — already landed in #2718 for both the Jira and GitLab skills. No Jira changes are needed.

Why this is not cosmetic

die() was already redaction-safe: it routed through _emit(), so the raw-stderr leak described in the issue was fixed by #2718. The remaining problem was an internal contract violation. The GitLabError docstring stated that die() survives only for "the argument-parsing and command-dispatch layer, where no value is promised" — yet die() was being called from four helpers that do promise return values:

That is exactly the "silent None return" hazard the docstring warns against. The documented contract and the code disagreed, and nothing enforced the split.

What changed

• All 61 die() call sites now raise GitLabError(message, exit_code), preserving each original message and exit-code constant. Sites inside except blocks chain with from exc.
• die() is deleted; the now-unused NoReturn import is dropped.
• GitLabError's docstring is rewritten to describe the single-mechanism contract.
• 42 SystemExit test references are migrated across 7 files.
• New source contract: no raise SystemExit, no sys.exit(...), and no die definition outside the __main__ guard — with one negative case per predicate.

Behavior

Exit codes are unchanged. main() already caught GitLabError, emitted once via _emit(), and returned exc.exit_code, so no new error handling was introduced.

Two deliberate consequences, both improvements:

1. Library helpers now raise without emitting. Emission happens once, at the main() boundary, removing a double-emission path.
2. SystemExit is a BaseException and previously bypassed main() entirely. These failures now flow through main(), so GITLAB_DEBUG=1 shows a redacted traceback for argument-validation failures that previously printed only a one-line error.

Related Issue(s)

Closes #1555

Type of Change

Code & Documentation:

• Breaking change (fix or feature causing existing functionality to change)

Other:

• Script/automation (.ps1, .sh, .py)

die() was a public module attribute, so its removal is technically breaking for any external caller importing gitlab.die. The CLI surface, exit codes, and output format are unchanged.

Testing

Test migration

The migration was not a uniform substitution. Sites fell into three kinds:

No assertion was weakened to a bare pytest.raises(Exception). Every migrated site that checked an exit code still checks the same constant.

TestDie was removed. Its exact error: boom single-line assertion was not already covered elsewhere — test_emit_writes_exactly_one_stderr_line exercises _emit directly, and no test previously reached main()'s handler because SystemExit bypassed it. A replacement assertion was added to a converted main() test:

assert capsys.readouterr().err == "error: --fields is not valid with auth commands\n"

Validation status

npm run test:py could not execute locally. uv sync fails with os error 32 inside the OneDrive-synced workspace and os error 396 outside it, PyPI is unreachable with a TLS HandshakeFailure, and the existing skill virtualenvs hold a partially installed pytest. This predates the change and affects unrelated skills identically.

Because the suite could not run, acceptance criteria were verified directly against system Python: die is absent from the module, the source contract rejects all three synthetic violations and accepts the guarded sys.exit(main()), and no SystemExit reference remains outside the contract's own test fixtures.

Reviewers: please confirm the GitLab suite passes in CI before merging. That is the one gate not satisfied locally.

Checklist

Required Checks

• Documentation is updated (if applicable) — n/a, no doc-visible behavior change
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable) — see Type of Change
• Tests added for new functionality (if applicable)

Required Local Checks

• npm run validate:local
• npm run spell-check
• npm run lint:md-links

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

No new dependencies. No change to _redact, _REDACT_KEYS, _REDACT_PATTERNS, the emit helpers, AuthContext, the OAuth modules, or the audit sink. The existing print-ownership, LOGGER.exception, and two-owner credentialed-egress contracts pass unmodified.

Additional Notes

The path:line references in #1555 are stale — the skills moved from .github/skills/{jira,gitlab}/{jira,gitlab}/ to .github/skills/project-planning/{jira,gitlab}/ and both files roughly tripled in size. Worth correcting the issue body on close.

The PR validation failure on Asset Docs Validation was due to the shared PowerShell module installer assuming PSGallery was already registered on the runner. The installer now self-registers PSGallery on demand, and the fix is covered by focused tests in scripts/tests/security/Install-PSModules.Tests.ps1.
Coverage follow-up for review thread 3850925767: the complete production-only Ubuntu run now passes 288 tests with 87.70% line coverage (1,062/1,211), 78.86% branch coverage (317/402), and 85.49% combined coverage. The terminal report publishes missing lines and partial branches for each runtime module: _gitlab_credentials.py 84%, _gitlab_oauth.py 79%, and gitlab.py 88%. The GitLab project now measures branches across scripts, reports missing lines, and enforces an 80% combined floor through the existing pytest CI lane. A focused regression also verifies typed GitLabError exit-code propagation, single redacted emission, and debug-traceback delegation at main().